home *** CD-ROM | disk | FTP | other *** search
/ EnigmA Amiga Run 1997 May / EnigmA AMIGA RUN 18 (1997)(G.R. Edizioni)(IT)[!][issue 1997-05][EAR-CD II].iso / softwareupdate / system / amigados / advancedroutines / advancedroutines.doc next >
Text File  |  1996-10-10  |  29KB  |  914 lines
  1. 7    ADVANCED ROUTINES
  2.  
  3. 7.1  INTRODUCTION
  4.  
  5. In this chapter I will describe some advanced routines in
  6. AmigaDOS. Although this chapter is mainly intended for
  7. experienced programmers I have tried to make it as easy as
  8. possible to read even if you are new C programmer and have
  9. not worked so much with AmigaDOS.
  10.  
  11.  
  12.  
  13. 7.2  GET INFORMATION ABOUT FILES AND DIRECTORIES
  14.  
  15. In some occations you might need to get some information about
  16. a file or directory. You might want to see which protection
  17. bits are currently set, how big the it is, on what date it was
  18. created, what comment is attached and so on... To get this type
  19. of information you should use the "Examine()" function.
  20.  
  21. Examine() allows you to examine files, directories and volumes.
  22. In the following sections I will now and then refer to all of
  23. these types as "objects".
  24.  
  25. There are two things you have to do before you can call
  26. Examine():
  27.  
  28.   1. You must lock the object you want to examine. Simply use
  29.      the Lock() function as previously explained. 
  30.  
  31.   2. Create a FileInfoBlock structure. The problem with this
  32.      structure is that it is used by AmigaDOS directly and must
  33.      therefore be long word aligned! (Since you have to create
  34.      the structure you must make sure that it is long word
  35.      aligned. Structures that are created by AmigaDOS itself
  36.      will always be long word aligned.)
  37.  
  38.  
  39.  
  40. 7.2.1  LOCK THE OBJECT
  41.  
  42. First you have to lock the object you want to examine with help
  43. of the Lock() function. Since we will only examine the object
  44. (read some values) it is enough with a shared lock ("read
  45. lock"). 
  46.  
  47. Here is an example:
  48.  
  49.   /* A "BCPL" pointer to our lock: */
  50.   BPTR my_lock;
  51.  
  52.   - - -
  53.  
  54.   /* Try to lock the object we later will examine: */
  55.   my_lock = Lock( "RAM:Highscore.dat", SHARED_LOCK );
  56.  
  57.   /* Check if we have successfully locked the object or not: */
  58.   if( my_lock == NULL )
  59.     printf( "Could not lock the object!\n" );
  60.  
  61.  
  62.  
  63. 7.2.2  CREATE A FILE INFO BLOCK
  64.  
  65. Before we can call Examine() we must also create a
  66. FileInfoBlock structure. This structure must, as already
  67. explained, be long word aligned ("a present from the wonderful
  68. BCPL language"). How we should create this structure depends
  69. on if your program should be compatible with the old dos
  70. libraries (WB1.2 and WB1.3) or not.
  71.  
  72.  
  73.  
  74. 7.2.2.1  OLD DOS VERSIONS (WB1.3 OR WB1.2)
  75.  
  76. If your program should be able to run on the old systems (dos
  77. libraries older than V37) you should allocate the
  78. FileInfoStructure with help of the AllocMem() function.
  79.  
  80. Here is an example:
  81.  
  82.   /* Declare a pointer to a FileInfoBlock structure: */
  83.   struct FileInfoBlock *my_fib_ptr;
  84.  
  85.   - - -
  86.  
  87.   /* Allocate enough memory for a FileInfoBlock structure: */
  88.   /* (OK! This memory will be long word aligned.)          */
  89.   my_fib_ptr = (struct FileInfoBlock *)
  90.     AllocMem( sizeof( struct FileInfoBlock ), MEMF_ANY | MEMF_CLEAR );
  91.  
  92.   /* Check if we have allocated the memory successfully: */
  93.   if( my_fib_ptr == NULL )
  94.     printf( "Could not allocate enough memory!\n" );
  95.  
  96.  
  97.  
  98. 7.2.2.2  NEW RELEASE 2 (WB2.04) OR HIGHER
  99.  
  100. If your program only should be used on systems with dos library
  101. V37 or higher (WB2.04 or higher) you should use the new
  102. AllocDosObject() function which is defined like this:
  103.  
  104. ---------------------------------------------------------------
  105.  
  106. AllocDosObject()
  107.  
  108. ROM library: "dos.library/AllocDosObject", (V37+)
  109. #include <clib/dos_protos.h>
  110.  
  111. Allocates different types of objects used by AmigaDOS. The
  112. objects will be long word aligned, and the size can vary
  113. between different dos library releases.
  114.  
  115. Synopsis: object = AllocDosObject( type, tags );
  116.  
  117.   object: (APTR) The function will return a pointer to the new
  118.           allocated object, or NULL if the object could not be
  119.           created.
  120.  
  121.   types:  (ULONG) The type of object you want to allocate:
  122.           (defined in header file "dos/dos.h")
  123.   
  124.             DOS_FIB          FileInfoBlock structure.
  125.  
  126.             DOS_FILEHANDLE   When you want to create your own
  127.                              file handler. Rarely used.
  128.  
  129.             DOS_EXALLCONTROL To create an object used by the
  130.                              ExAll() function. (See below for
  131.                              more information)
  132.  
  133.             DOS_STDPKT       When you want a "standard AmigaDOS
  134.                              Packets".
  135.  
  136.             DOS_CLI          Object needed when you write
  137.                              your own Shells.
  138.  
  139.             DOS_RDARGS       Used by the command line parsing
  140.                              routines as described in chapter 5
  141.                              "Parsing the Command Line".
  142.   
  143.   tags:   (struct TagItem *) Pointer to a list of one or more
  144.           TagItem structures which has been initialized with
  145.           your requirements, or NULL if you do not want to set
  146.           any tags.
  147.           
  148.           This tag filed is currently only used when you write
  149.           your own file handlers or Shells. The available tags
  150.           are listed in header file "dos/dos.h", but since they
  151.           are rarely used with this function I have not listed
  152.           them here. As always the last "Tag ID" must be
  153.           "TAG_DONE".
  154.           
  155.           
  156. Since this function uses the new "Tag Sytem" there exist two
  157. other options on how to call the function:
  158.  
  159. Synopsis: object = AllocDosObjectTagList( type, tags );
  160.  
  161.   This one is identical to the "AllocDosObject()" function
  162.   which we have just described. See above for information about
  163.   the arguments.
  164.  
  165. Synopsis: object = AllocDosObjectTags( type, tag1, tag2, ... );
  166.  
  167.   Similar to "AllocDosObject()", but instead of giving the
  168.   function a pointer to a list of TagItem structures you list
  169.   all tags as arguments for the function. Note that the last
  170.   "Tag ID" must as always be "TAG_DONE".
  171.  
  172.   tag1: (ULONG) The ID for tag 1.
  173.  
  174.   tag2: (ULONG) The Data for tag 1.
  175.  
  176.   tag3: (ULONG) The ID for tag 2.
  177.  
  178.   - - - and so on...
  179.  
  180.   tagX: (ULONG) The ID for tag X, must be "TAG_DONE".
  181.  
  182.  
  183. Note! All objects which are allocated with help of the
  184. AllocDosObject() function must when not needed any more be
  185. deallocated with help of the FreeDosObject() function.
  186.  
  187. Here is a simple example on how to use the AllocDosObject()
  188. function:
  189.  
  190.   /* Declare a pointer to our FileInfoBlock */
  191.   /* which we will allocate:                */
  192.   struct FileInfoBlock *my_fib;
  193.  
  194.   - - -
  195.  
  196.   /* Create a FileInfoBlock structure with help */
  197.   /* of the new AllocDosObject() function:      */
  198.   my_fib = AllocDosObject( DOS_FIB, NULL );
  199.  
  200.   /* Check if we have allocated the memory successfully: */
  201.   if( !my_fib )
  202.     printf( "Could not allocate the FileInfoBlock!\n" );
  203.  
  204.  
  205. See also: Examine(), FreeDosObject()
  206.  
  207. ---------------------------------------------------------------
  208.  
  209.  
  210.  
  211. 7.2.3  CALL EXAMINE()
  212.  
  213. Once you have locked the object you want to examine and you
  214. have allocated a FileInfoBlock structure you may call the
  215. Examine() function.
  216.  
  217. ---------------------------------------------------------------
  218.  
  219. Examine()
  220.  
  221. ROM library: "dos.library/Examine", (All versions)
  222. #include <clib/dos_protos.h>
  223.  
  224. Examines a file, direcotry, volume (or device) and stores some
  225. interesting information about the object in a given
  226. FileInfoBlock structure.
  227.  
  228. Synopsis: ok = Examine( lock, fib );
  229.  
  230.   ok:     (LONG) If the function managed to examine the object
  231.           it returns "DOSTRUE". On the other hand, if the
  232.           function failed to get the information it returns
  233.           "DOSFALSE".
  234.   
  235.   lock:   (BPTR) A BCPL pointer to the lock on the object you
  236.           want to examine. 
  237.   
  238.   fib:    (struct FileInfoBlock *) Pointer to a FileInfoBlock
  239.           structure in which all information will be stored.
  240.           This structure must be long word aligned.
  241.  
  242. Here is a simple example on how to use the Examine() function:
  243.  
  244.   /* AmigaDOS boolean check variable: */
  245.   LONG ok;
  246.  
  247.   - - -
  248.  
  249.   /* Get some information about an object: */
  250.   ok = Examine( my_lock, my_fib );
  251.  
  252.   /* Could we get the information? */
  253.   if( !ok )
  254.     printf( "Error! Could not examine the object!\n" );
  255.   else
  256.     printf( "OK! You may examine the FileInfoBlock structure" );
  257.  
  258.  
  259. See also: AllocDosObject(), AllocMem(), ExNext(),
  260.           FreeDosObject()
  261.  
  262. ---------------------------------------------------------------
  263.  
  264.  
  265.  
  266. 7.2.4  EXAMINE THE FILE INFO BLOCK
  267.  
  268. If you have successfully examined the object you may look at
  269. the different fields in the FileInfoBlock structure. The
  270. structure is defined in header file "dos/dos.h" like this:
  271.  
  272.   struct FileInfoBlock
  273.   {
  274.     LONG fib_DiskKey;
  275.     LONG fib_DirEntryType;
  276.     char fib_FileName[108];
  277.     LONG fib_Protection;
  278.     LONG fib_EntryType;
  279.     LONG fib_Size;
  280.     LONG fib_NumBlocks;
  281.     struct DateStamp fib_Date;
  282.     char fib_Comment[80];
  283.     char fib_Reserved[36];
  284.   };
  285.  
  286. fib_DiskKey:      Key number for the disk. Usually of no
  287.                   interest for us.
  288.  
  289. fib_DirEntryType: If the number is smaller than zero it is a
  290.                   file. On the other hand, if the number is
  291.                   larger than zero it is a directory (or volume
  292.                   or device).
  293.  
  294.                     /* Is it a file or directory (etc)? */
  295.                     if( my_fib->fib_DirEntryType < 0 )
  296.                       printf( "File\n" );
  297.                     else
  298.                       printf( "Directory or Volume\n" );
  299.  
  300. fib_FileName:     Null terminated string containing the file-
  301.                   name. (File names may not be longer than 30
  302.                   characters.)
  303.  
  304. fib_Protection:   Field containing the protection flags:
  305.                   (if set)
  306.  
  307.                   FIBF_DELETE  : the file/directory can not be
  308.                                  deleted.
  309.                   FIBF_EXECUTE : the file can not be executed.
  310.                   FIBF_WRITE   : you can not write to the file.
  311.                   FIBF_READ    : you can not read the file.
  312.                   FIBF_ARCHIVE : Archive bit.
  313.                   FIBF_PURE    : Pure bit.
  314.                   FIBF_SCRIPT  : Script bit.
  315.  
  316.                     /* Is the object protected: */
  317.                     if( my_fib->fib_Protection & FIBF_DELETE )
  318.                       printf( "Protected!" );
  319.                     else
  320.                       printf( "Not protected!" );
  321.  
  322. fib_EntryType:    File/Directory entry type number. Usually of no
  323.                   interest for us.
  324.  
  325. fib_Size:         Size of the file (in bytes).
  326.  
  327. fib_NumBlocks:    Number of blocks in the file.
  328.  
  329. fib_Date:         Structure containing the date when the file
  330.                   was latest updated/created. See below for
  331.                   more information.
  332.  
  333. fib_Comment:      Null terminated string containing a comment.
  334.                   (Max 80 characters including the NULL sign.)
  335.  
  336. fib_Reserved:     This field is for the moment reserved, and may
  337.                   therefore not be used.
  338.  
  339.  
  340. The DateStamp structure which is a part of the FileInfoBlock
  341. structure is also defined in header file "dos/dos.h", and looks
  342. like this:
  343.  
  344.   struct DateStamp
  345.   {
  346.     LONG ds_Days;
  347.     LONG ds_Minute;
  348.     LONG ds_Tick;
  349.   };
  350.   
  351. ds_Days:   Number of days since 01-Jan-1978.
  352.  
  353. ds_Minute: Number of minutes past midnight.
  354.  
  355. ds_Tick:   Number of ticks past the last minute. There are 50
  356.            ticks / second. (50 * 60 = 3000 ticks / minute.)
  357.  
  358.  
  359. See the examples for a complete list of how to examine the
  360. FileInfoBlock structure.
  361.  
  362.  
  363.  
  364. 7.2.5  CLEAN UP
  365.  
  366. Once you have examined the FileInfoBlock structure and do not
  367. want to use it any more you should deallocate it. If you 
  368. allocated it with help of AllocMem() you must free it with help
  369. of FreeMem():
  370.  
  371.   /* Deallocate the memory when we do not need it any more: */
  372.   FreeMem( my_fib_ptr, sizeof( struct FileInfoBlock ) );
  373.  
  374.  
  375. However, if you allocated the structure with help of the new
  376. AllocDosObject() function you have to use the FreeDosObject()
  377. function to deallocate the structure. The FreeDosObject()
  378. function is defined like this:
  379.  
  380. ---------------------------------------------------------------
  381.  
  382. FreeDosObject()
  383.  
  384. ROM library: "dos.library/FreeDosObject", (V37+)
  385. #include <clib/dos_protos.h>
  386.  
  387. Deallocates objects that was created by a previous call to the
  388. AllocDosObject() function.
  389.  
  390. Synopsis: FreeDosObject( type, tags );
  391.  
  392.   types:  (ULONG) The type of object that should be
  393.           deallocated: (You must of course use the same type
  394.           as when you allocated the object. See function
  395.           AllocDosObject() for more information about the
  396.           available types.)  
  397.  
  398.             DOS_FIB         
  399.             DOS_FILEHANDLE  
  400.             DOS_EXALLCONTROL
  401.             DOS_STDPKT      
  402.             DOS_CLI         
  403.             DOS_RDARGS      
  404.   
  405.   object: (APTR) Pointer to the object that should be
  406.           deallocated.
  407.           
  408. Note! All objects which are allocated with help of the
  409. AllocDosObject() function must when not needed any more be
  410. deallocated with help of this FreeDosObject() function.
  411.  
  412. Note! Only objects which were created by AllocDosObject() may
  413. be deallocated with this function.
  414.  
  415. Here is a simple example on how to use the FreeDosObject()
  416. function:
  417.  
  418.   - - -
  419.  
  420.   /* Deallocate the FileInfoBlock structure wich we have */
  421.   /* created with help of the AllocDosObject() function: */
  422.   FreeDosObject( DOS_FIB, my_fib );
  423.  
  424.  
  425. See also: AllocDosObject(), Examine()
  426.  
  427. ---------------------------------------------------------------
  428.  
  429. You must of course also unlock the object when you do not need
  430. it any more. Example:
  431.  
  432.   /* Unlock the object: */
  433.   UnLock( my_lock );
  434.  
  435.  
  436.  
  437. 7.3  EXAMINE FILES/SUBDIRECTORIES IN A DIRECTORY/DEVICE
  438.  
  439. A directory, volume or device (I will refer to them all as
  440. "directories") can contain several files as well as several
  441. (sub)directories. If you want to examine all objects in a
  442. directory you should first use the Examine() function to
  443. examine the directory.
  444.  
  445. If you discover that the current object is a directory you
  446. can use a function called ExNext() to get information about
  447. the objects in the directory. The first time you call ExNext()
  448. you will get information about the first object in the
  449. directory. You can then call ExNext() again to get information
  450. about the next object and so on until there are no more objects
  451. left to examine and the ExNext() function fails.
  452.  
  453. It it important to remember that ExNext() can only be called
  454. after you first have successfully called Examine(), and you
  455. must use the same FileInfoBlock structure each time.
  456.  
  457. The ExNext() function is very similar to Examine() and is
  458. defined like this:
  459.  
  460. ---------------------------------------------------------------
  461.  
  462. ExNext()
  463.  
  464. ROM library: "dos.library/ExNext", (All versions)
  465. #include <clib/dos_protos.h>
  466.  
  467. Examines objects in a directory, device, or volume. Can be
  468. called several times until there are no more objects to
  469. examine.
  470.  
  471. Synopsis: ok = ExNext( lock, fib );
  472.  
  473.   ok:     (LONG) If the function managed to examine the object
  474.           it returns "DOSTRUE". On the other hand, if the
  475.           function failed to get the information it returns
  476.           "DOSFALSE".
  477.           
  478.           When this function fails you should call the IoErr()
  479.           function to get more information about the error. If
  480.           IoErr() returns "ERROR_NO_MORE_ENTRIES" there were
  481.           simply no more objects in the directory (device/
  482.           volume), but if IoErr() returns anything else there
  483.           was some sort of "real" error.
  484.  
  485.   lock:   (BPTR) A BCPL pointer to the lock you used when you
  486.           first called Examine().
  487.   
  488.   fib:    (struct FileInfoBlock *) Pointer to a FileInfoBlock
  489.           structure in which all information will be stored.
  490.           This structure must be long word aligned, and you
  491.           may not alter any of the fields while you are
  492.           collecting objects. You may only read the values,
  493.           not modify them!
  494.  
  495. After you have successfully examined a directory, device or
  496. volume with help of the Examine() function you can use this
  497. function to get information about the objects in that
  498. directory, device or volume. To examine all objects simply
  499. call this function over and over again until it fails because
  500. there are no more objects left to examine, or there was some
  501. sort of error.
  502.  
  503. Here is a simple example on how to use the ExNext() function:
  504. (You must of course first have called the Examine() function
  505. and checked that it really is a directory (device or volume)
  506. before you may call ExNext().)
  507.  
  508.   - - -
  509.   
  510.   /* As long as we find objects we stay in the loop and */
  511.   /* prints the name of the objects we find:            */
  512.   while( ExNext( my_lock, my_fib ) )
  513.     printf( "%s\n", my_fib->fib_FileName );
  514.  
  515.   /* The ExNext() function has now failed. Check if it simply */
  516.   /* was no more objects left to examine or if there really   */
  517.   /* was an error:                                            */
  518.   if( IoErr() == ERROR_NO_MORE_ENTRIES )
  519.     printf( "OK! No more files!\n" );
  520.   else
  521.     printf("Error while reading!\n");
  522.  
  523.  
  524. See also: Examine()
  525.  
  526. ---------------------------------------------------------------
  527.  
  528.  
  529.  
  530. 7.4  GET INFORMATION ABOUT A DISK
  531.  
  532. To get information about a disk you must first create an
  533. "InfoData" structure in which all information will be stored.
  534. As you probably already have guessed this structure must be
  535. long word aligned. Once you have created the structure you
  536. should lock the disk you want to examine and finally call
  537. the "Info()" function.
  538.  
  539.  
  540.  
  541. 7.4.1  CREATE THE INFODATA STRUCTURE
  542.  
  543. Since the InfoData structure has to be long word aligned you
  544. have to use AllocMem() to create it. (AllocDosObject() does not
  545. support this type of object.) 
  546.  
  547. Here is an example:
  548.  
  549.   /* Declare a pointer to our */
  550.   /* info data block:         */
  551.   struct InfoData *my_info_data;
  552.  
  553.   - - -
  554.  
  555.   /* Allocate memory for an InfoData structure: */
  556.   my_info_data = (struct InfoData *)
  557.     AllocMem( sizeof( struct InfoData ), MEMF_ANY );
  558.  
  559.   /* Have we successfully allocated the memory? */
  560.   if( !my_info_data )
  561.     printf( "Could not allocate enough memory!\n" );
  562.  
  563.  
  564.  
  565. 7.4.2  LOCK THE DISK
  566.  
  567. Once you have created an InfoData structure you should lock
  568. the disk you want to examine. (Of course the order does not
  569. matter and you could equally well have first locked the disk
  570. and then allocated the InfoData structure.) Since we will only
  571. look at the disk it is enough with a shared lock.
  572.  
  573. Here is an example:
  574.  
  575.   /* A "BCPL" pointer to our lock: */
  576.   BPTR my_lock;
  577.  
  578.   - - -
  579.  
  580.   /* Lock the disk (in this case "df0:"): */
  581.   my_lock = Lock( "df0:", SHARED_LOCK );
  582.  
  583.   /* Have we successfully locked the disk? */
  584.   if( !my_lock )
  585.     printf( "Could not lock the disk!\n" );
  586.  
  587.  
  588.  
  589. 7.4.3  CALL THE INFO() FUNCTION
  590.  
  591. At last we can call the Info() function to examine the disk.
  592. The Info() function is defined like this:
  593.  
  594. ---------------------------------------------------------------
  595.  
  596. Info()
  597.  
  598. ROM library: "dos.library/Info", (All versions)
  599. #include <clib/dos_protos.h>
  600.  
  601. Examines a disk and stores some interesting information about
  602. it in an InfoData structure.
  603.  
  604. Synopsis: ok = Info( lock, info );
  605.  
  606.   ok:     (LONG) If the function managed to examine the disk
  607.           it returns "DOSTRUE". On the other hand, if the
  608.           function failed to get the information it returns
  609.           "DOSFALSE".
  610.           
  611.   lock:   (BPTR) A BCPL pointer to a lock on the disk you want
  612.           to examine.
  613.   
  614.   info:   (struct InfoData *) Pointer to an InfoData structure
  615.           which will be used to store all information in.
  616.           Please note that since you have to supply this
  617.           function with your own structure is must be long
  618.           word aligned! 
  619.  
  620. Here is a simple example on how to use the Info() function:
  621.  
  622.  
  623.   /* If the function was successful or not: */
  624.   LONG ok;
  625.  
  626.   - - -
  627.  
  628.   /* Examine the disk: */
  629.   ok = Info( my_lock, my_info_data );
  630.   if( ok )
  631.   {  
  632.     /* Print some info about the disk: */
  633.     if( my_info_data->id_DiskState == ID_WRITE_PROTECTED )
  634.       printf( "The disk is Write Protected!\n" );
  635.  
  636.     if( my_info_data->id_DiskState == ID_VALIDATED )
  637.       printf( "The disk is Not (Write) Protected!\n" );
  638.   }
  639.   else
  640.     printf( "Could not examine the disk!\n" );
  641.  
  642.  
  643. See also: AllocMem(), Lock()
  644.  
  645. ---------------------------------------------------------------
  646.  
  647.  
  648.  
  649. 7.4.4 INFODATA STRUCTURE
  650.  
  651. If you have successfully called the Info() function you can
  652. start to examine the fields in the InfoData structure which has
  653. now been initialized. The InfoData structure is defined in
  654. header file "dos/dos.h" like this:
  655.  
  656.   struct InfoData
  657.   {
  658.      LONG    id_NumSoftErrors;
  659.      LONG    id_UnitNumber;
  660.      LONG    id_DiskState;
  661.      LONG    id_NumBlocks;
  662.      LONG    id_NumBlocksUsed;
  663.      LONG    id_BytesPerBlock;
  664.      LONG    id_DiskType;
  665.      BPTR    id_VolumeNode;
  666.      LONG    id_InUse;
  667.   };
  668.  
  669. id_NumSoftErrors: Number of soft errors on the disk. (Number
  670.                   of damaged areas.)
  671.  
  672. id_UnitNumber:    In which unit the disk is in. (Note that it
  673.                   might have been removed after you have called
  674.                   the Info().)
  675.  
  676. id_DiskState:     The disk can have one of the following three
  677.                   different states:
  678.                   
  679.                   ID_VALIDATING      The disk has just been
  680.                                      inserted and AmigaDOS is
  681.                                      trying to see what type of
  682.                                      disk it really is. (This
  683.                                      flag can also be set if
  684.                                      the disk is damaged, or
  685.                                      there are internal problems
  686.                                      in the filing system.)
  687.                                      
  688.                                      The disk can for the
  689.                                      moment not be used when
  690.                                      it is in this state.
  691.  
  692.                   ID_VALIDATED       The disk has been
  693.                                      validated, and the disk
  694.                                      is NOT write protected.
  695.                                      
  696.                   ID_WRITE_PROTECTED The disk has been
  697.                                      validated, and the disk
  698.                                      is write protected.
  699.  
  700. id_NumBlocks:     Number of blocks on the disk.
  701.  
  702. id_NumBlocksUsed: Number of blocks used.
  703.  
  704. id_BytesPerBlock: Size (in bytes) of each block.
  705.  
  706. id_DiskType:      There exist several different types of disks:
  707.  
  708.                   ID_NO_DISK_PRESENT No disk in the drive.
  709.                                      (Interesting type of disk.)
  710.  
  711.                   ID_UNREADABLE_DISK The disk contains corrupted
  712.                                      data and can not be used.
  713.  
  714.                   ID_DOS_DISK        It is a normal disk.
  715.  
  716.                   ID_FFS_DISK        The disk is using the
  717.                                      "Fast Filing System" (FFS)
  718.  
  719.                   ID_INTER_DOS_DISK  It is a normal int. disk.
  720.  
  721.                   ID_INTER_FFS_DISK  The int. disk is using the
  722.                                      "Fast Filing System" (FFS)
  723.  
  724.                   ID_NOT_REALLY_DOS  Not a dos (normal) disk.
  725.  
  726.                   ID_KICKSTART_DISK  It is a "Kickstart" disk.
  727.                                      Special type of disk used
  728.                                      on A1000 to load the
  729.                                      system which is on the
  730.                                      other Amiga models included
  731.                                      in the Kickstart ROMs.
  732.  
  733.                   ID_MSDOS_DISK      It is an (IBM) MS dos
  734.                                      disk. (The special program
  735.                                      "CrossDos" which is
  736.                                      included with WB 2.1 allows
  737.                                      the user to also work with
  738.                                      MS dos disks - 720 kB.)
  739.  
  740. id_VolumeNode:    Pointer to the volume node list which is
  741.                   rarely used.
  742.  
  743. id_InUse:         If this field is non zero ths disk is in use.
  744.                   (Since you must have locked the disk before
  745.                   you could examine it, this field will always
  746.                   be non zero since at least your program is
  747.                   using the disk.)
  748.  
  749.  
  750.  
  751. 7.5  THE INTERNAL ASSIGN, VOLUME AND DEVICE LIST
  752.  
  753. AmigaDOS has a list of all Assigns, Volumes and Devices it
  754. currently knows about. Whenever a disk is inserted or removed,
  755. a new assign is added etc... this list is automatically
  756. updated.
  757.  
  758. As a programmer you migh need to know which assigns, volumes or
  759. devices are currently available. A file requester should for
  760. example be able to display this list so the user can directly
  761. select the device, assign or volume he/she wants to go to.
  762.  
  763. If you want to get the names of all objects AmigaDOS currently
  764. knows about, and you want your program to be compatible with
  765. all dos library versions, you have to go deep down into the
  766. system. However, as long as you know what you are doing (or
  767. follows my steps carefully) there is danger and we are not
  768. breaking any "programming laws" by doing this.
  769.  
  770. This is what you have to do:
  771.  
  772.   1. Get a pointer to the dos library. We simply declare the
  773.      global dos library pointer as external, and it will
  774.      automatically be initialized for us as explained earlier.
  775.        
  776.        /* Declare an external global library */
  777.        /* pointer to the Dos library:        */
  778.        extern struct DosLibrary *DOSBase;
  779.  
  780.  
  781.   2. In the DosLibrary structure you will find a pointer to
  782.      a "RootNode" structure. This strucure contains some 
  783.      fundamental parts of AmigaDOS but shold not be used
  784.      unless you really know what you are dowing. 
  785.  
  786.        /* Declare a pointer to the RootNode structure: */
  787.        struct RootNode *rootnode_ptr;
  788.  
  789.        - - -
  790.  
  791.        /* Get a pointer to the RootNode structure: */
  792.        rootnode_ptr = DOSBase->dl_Root;
  793.   
  794.   
  795.   3. In the RootNode structure we can find a BCPL pointer to
  796.      a DosInfo structure.
  797.  
  798.        /* Declare a temporary BCPL pointer used */
  799.        /* to convert BPTRs into C pointer with: */
  800.        BPTR temp_bptr;
  801.  
  802.        - - -
  803.  
  804.        /* Get a BCPL pointer (BPTR) to */
  805.        /* the DosInfo structure:       */
  806.        temp_bptr = rootnode_ptr->rn_Info;
  807.  
  808.  
  809.   4. Since you got a BPTR (a BCPL pointer) you must convert it
  810.      into a normal C pointer before you can use it. (BCPL
  811.      pointers are four times "smaller" than normal C pointers
  812.      and it must therefore be multiplied by 4, which is done
  813.      with help of the BADDR() macro.)
  814.  
  815.        /* Declare a pointer to a DosInfo structure: */
  816.        struct DosInfo *dos_info_ptr;
  817.         
  818.        - - -
  819.         
  820.        /* Convert the BCPL pointer into a normal C pointer: */
  821.        dos_info_ptr = (struct DosInfo *) BADDR( temp_bptr );
  822.  
  823.  
  824.   5. It is in this DosInfo structure you will find a linked
  825.      list of "DosList" nodes. In each DosList node you will
  826.      find the name of one device, assign or volume. However,
  827.      before you may scan the linked list you have to "lock" it
  828.      so it does not change while you are reading it. If the
  829.      user inserts or removes a disk for example the list will
  830.      be rebuilt and nodes may be added or taken away, and this
  831.      must of course not happen while you are in the middle of
  832.      the linked list!
  833.  
  834.      On the older dos libraries, prior to V36, there does not
  835.      exist any function to directly lock the list. Instead you
  836.      have to use the system function "Forbid()" which will turn
  837.      off some parts of the multitasking. (Note that while you
  838.      are in this "forbidden" mode you may not use any Wait()
  839.      calls, and you should as quickly as possible return to
  840.      normal state.)
  841.      
  842.        /* Turn off parts of the multitasking: */
  843.        Forbid();
  844.  
  845.  
  846.   6. You can now scan the list of "DosList" nodes. Each DosList
  847.      node (structure) has a pointer to the next node. In the
  848.      last node this pointer is pointing NULL. (Note that while
  849.      you are examining the nodes you have to convert a lot
  850.      of BCPL pointers into normal C pointers.)
  851.  
  852.        /* Decalre pointer to the first DosList structure: */
  853.        struct DosList *first_doslist_node;
  854.  
  855.        /* Decalre a pointer to the current (the one */
  856.        /* we are working with) DosList structure:   */
  857.        struct DosList *doslist_node;
  858.  
  859.        - - -
  860.  
  861.        /* Get a BCPL pointer (BPTR) to the */
  862.        /* first "DosList" node:            */
  863.        temp_bptr = dos_info_ptr->di_DevInfo;
  864.  
  865.        /* Convert the BPTR into a C pointer: */
  866.        first_doslist_node = (struct DosList *)
  867.          BADDR( temp_bptr );
  868.  
  869.        /* Start with the first node: */
  870.        doslist_node = first_doslist_node;
  871.  
  872.        /* Stay in the loop until all */
  873.        /* nodes have been checked:   */
  874.        while( doslist_node )
  875.        {
  876.  
  877.          - - -
  878.  
  879.          /* Examine the node... */
  880.  
  881.          - - -
  882.  
  883.          /* Go to next node: */
  884.          
  885.          /* Get a BPTR to the next node: */
  886.          temp_bptr = doslist_node->dol_Next;
  887.     
  888.          /* Convert the BPTR into a C pointer: */
  889.          doslist_node = (struct DosList *)
  890.            BADDR( temp_bptr );
  891.        }
  892.  
  893.  
  894.   7. When all nodes have been examined you should as quickly as
  895.      possible turn on the multitasking by calling the "Permit()"
  896.      function.
  897.   
  898.        /* Turn the multitaskin ON again: */
  899.        Permit();
  900.  
  901. easy as pie... 
  902.  
  903.  
  904.  
  905. 7.6  TO BE CONTINUED...
  906.  
  907. There are of course a lot of other advanced and interesting
  908. things you can do with AmigaDOS, but that will be added in
  909. coming updates... Remember to pay the registration fee so you
  910. do not miss future updates!
  911.  
  912.                     TO BE CONTINUED....(!)
  913.  
  914.